git - the stupid content tracker

Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals.

See the section called “gittutorial(7)” to get started, then see the section called “giteveryday(7)” for a useful minimum set of commands. The Git User's Manual has a more in-depth introduction.

After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about individual Git commands with "git help command". the section called “gitcli(7)” manual page gives you an overview of the command-line command syntax.

A formatted and hyperlinked copy of the latest Git documentation can be viewed at https://git.github.io/htmldocs/git.html or https://git-scm.com/docs.

We divide Git into high level ("porcelain") commands and low level ("plumbing") commands.

We separate the porcelain commands into the main commands and some ancillary user utilities.

Although Git includes its own porcelain layer, its low-level commands are sufficient to support development of alternative porcelains. Developers of such porcelains might start by reading about the section called “git-update-index(1)” and the section called “git-read-tree(1)”.

The interface (input, output, set of options and the semantics) to these low-level commands are meant to be a lot more stable than Porcelain level commands, because these commands are primarily for scripted use. The interface to Porcelain commands on the other hand are subject to change in order to improve the end user experience.

The following description divides the low-level commands into commands that manipulate objects (in the repository, index, and working tree), commands that interrogate and compare objects, and commands that move objects and references between repositories.

The following documentation pages are guides about Git concepts.

This documentation discusses repository and command interfaces which users are expected to interact with directly. See --user-formats in the section called “git-help(1)” for more details on the criteria.

This documentation discusses file formats, over-the-wire protocols and other git developer interfaces. See --developer-interfaces in the section called “git-help(1)”.

Git uses a simple text format to store customizations that are per repository and are per user. Such a configuration file may look like this:

#
# A '#' or ';' character indicates a comment.
#

; core variables
[core]
        ; Don't trust file modes
        filemode = false

; user identity
[user]
        name = "Junio C Hamano"
        email = "gitster@pobox.com"

Various commands read from the configuration file and adjust their operation accordingly. See the section called “git-config(1)” for a list and more details about the configuration mechanism.

Any Git command accepting any <object> can also use the following symbolic notation:

For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in the section called “gitrevisions(7)”.

Please see the the section called “gitrepository-layout(5)” document.

Read the section called “githooks(5)” for more details about each hook.

Higher level SCMs may provide and manage additional information in the $GIT_DIR.

Please see the section called “gitglossary(7)”.

Various Git commands pay attention to environment variables and change their behavior. The environment variables marked as "Boolean" take their values the same way as Boolean valued configuration variables, i.e., "true", "yes", "on" and positive numbers are taken as "yes", while "false", "no", "off", and "0" are taken as "no".

Here are the variables:

More detail on the following is available from the Git concepts chapter of the user-manual and the section called “gitcore-tutorial(7)”.

A Git project normally consists of a working directory with a ".git" subdirectory at the top level. The .git directory contains, among other things, a compressed object database representing the complete history of the project, an "index" file which links that history to the current contents of the working tree, and named pointers into that history such as tags and branch heads.

The object database contains objects of three main types: blobs, which hold file data; trees, which point to blobs and other trees to build up directory hierarchies; and commits, which each reference a single tree and some number of parent commits.

The commit, equivalent to what other systems call a "changeset" or "version", represents a step in the project's history, and each parent represents an immediately preceding step. Commits with more than one parent represent merges of independent lines of development.

All objects are named by the SHA-1 hash of their contents, normally written as a string of 40 hex digits. Such names are globally unique. The entire history leading up to a commit can be vouched for by signing just that commit. A fourth object type, the tag, is provided for this purpose.

When first created, objects are stored in individual files, but for efficiency may later be compressed together into "pack files".

Named pointers called refs mark interesting points in history. A ref may contain the SHA-1 name of an object or the name of another ref (the latter is called a "symbolic ref"). Refs with names beginning refs/head/ contain the SHA-1 name of the most recent commit (or "head") of a branch under development. SHA-1 names of tags of interest are stored under refs/tags/. A symbolic ref named HEAD contains the name of the currently checked-out branch.

The index file is initialized with a list of all paths and, for each path, a blob object and a set of attributes. The blob object represents the contents of the file as of the head of the current branch. The attributes (last modified time, size, etc.) are taken from the corresponding file in the working tree. Subsequent changes to the working tree can be found by comparing these attributes. The index may be updated with new content, and new commits may be created from the content stored in the index.

The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress.

Some configuration options and hook files may cause Git to run arbitrary shell commands. Because configuration and hooks are not copied using git clone, it is generally safe to clone remote repositories with untrusted content, inspect them with git log, and so on.

However, it is not safe to run Git commands in a .git directory (or the working tree that surrounds it) when that .git directory itself comes from an untrusted source. The commands in its config and hooks are executed in the usual way.

By default, Git will refuse to run when the repository is owned by someone other than the user running the command. See the entry for safe.directory in the section called “git-config(1)”. While this can help protect you in a multi-user environment, note that you can also acquire untrusted repositories that are owned by you (for example, if you extract a zip file or tarball from an untrusted source). In such cases, you'd need to "sanitize" the untrusted repository first.

If you have an untrusted .git directory, you should first clone it with git clone --no-local to obtain a clean copy. Git does restrict the set of options and hooks that will be run by upload-pack, which handles the server side of a clone or fetch, but beware that the surface area for attack against upload-pack is large, so this does carry some risk. The safest thing is to serve the repository as an unprivileged user (either via the section called “git-daemon(1)”, ssh, or using other tools to change user ids). See the discussion in the SECURITY section of the section called “git-upload-pack(1)”.

See the references in the "description" section to get started using Git. The following is probably more detail than necessary for a first-time user.

The Git concepts chapter of the user-manual and the section called “gitcore-tutorial(7)” both provide introductions to the underlying Git architecture.

See the section called “gitworkflows(7)” for an overview of recommended workflows.

See also the howto documents for some useful examples.

The internals are documented in the Git API documentation.

Users migrating from CVS may also want to read the section called “gitcvs-migration(7)”.

Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the Git mailing list <git@vger.kernel.org>. https://openhub.net/p/git/contributors/summary gives you a more complete list of contributors.

If you have a clone of git.git itself, the output of the section called “git-shortlog(1)” and the section called “git-blame(1)” can show you the authors for specific parts of the project.

Report bugs to the Git mailing list <git@vger.kernel.org> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there. See the list archive at https://lore.kernel.org/git for previous bug reports and other discussions.

Issues which are security relevant should be disclosed privately to the Git Security mailing list <git-security@googlegroups.com>.

the section called “gittutorial(7)”, the section called “gittutorial-2(7)”, the section called “giteveryday(7)”, the section called “gitcvs-migration(7)”, the section called “gitglossary(7)”, the section called “gitcore-tutorial(7)”, the section called “gitcli(7)”, The Git User's Manual, the section called “gitworkflows(7)”

Part of the the section called “git(1)” suite

git-add - Add file contents to the index

This command updates the index using the current content found in the working tree, to prepare the content staged for the next commit. It typically adds the current content of existing paths as a whole, but with some options it can also be used to add content with only part of the changes made to the working tree files applied, or remove paths that do not exist in the working tree anymore.

The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus after making any changes to the working tree, and before running the commit command, you must use the add command to add any new or modified files to the index.

This command can be performed multiple times before a commit. It only adds the content of the specified file(s) at the time the add command is run; if you want subsequent changes included in the next commit, then you must run git add again to add the new content to the index.

The git status command can be used to obtain a summary of which files have changes that are staged for the next commit.

The git add command will not add ignored files by default. If any ignored files were explicitly specified on the command line, git add will fail with a list of ignored files. Ignored files reached by directory recursion or filename globbing performed by Git (quote your globs before the shell) will be silently ignored. The git add command can be used to add ignored files with the -f (force) option.

Please see the section called “git-commit(1)” for alternative ways to add content to a commit.

When the command enters the interactive mode, it shows the output of the status subcommand, and then goes into its interactive command loop.

The command loop shows the list of subcommands available, and gives a prompt "What now> ". In general, when the prompt ends with a single >, you can pick only one of the choices given and type return, like this:

    *** Commands ***
      1: status       2: update       3: revert       4: add untracked
      5: patch        6: diff         7: quit         8: help
    What now> 1

You also could say s or sta or status above as long as the choice is unique.

The main command loop has 6 subcommands (plus help and quit).

Invoking git add -e or selecting e from the interactive hunk selector will open a patch in your editor; after the editor exits, the result is applied to the index. You are free to make arbitrary changes to the patch, but note that some changes may have confusing results, or even result in a patch that cannot be applied. If you want to abort the operation entirely (i.e., stage nothing new in the index), simply delete all lines of the patch. The list below describes some common things you may see in a patch, and which editing operations make sense on them.

There are also more complex operations that can be performed. But beware that because the patch is applied only to the index and not the working tree, the working tree will appear to "undo" the change in the index. For example, introducing a new line into the index that is in neither the HEAD nor the working tree will stage the new line for commit, but the line will appear to be reverted in the working tree.

Avoid using these constructs, or do so with extreme caution.

There are also several operations which should be avoided entirely, as they will make the patch impossible to apply:

Everything below this line in this section is selectively included from the the section called “git-config(1)” documentation. The content is the same as what's found there:

the section called “git-status(1)” the section called “git-rm(1)” the section called “git-reset(1)” the section called “git-mv(1)” the section called “git-commit(1)” the section called “git-update-index(1)”

Part of the the section called “git(1)” suite

git-am - Apply a series of patches from a mailbox

Splits mail messages in a mailbox into commit log messages, authorship information, and patches, and applies them to the current branch. You could think of it as a reverse operation of the section called “git-format-patch(1)” run on a branch with a straight history without merges.

The commit author name is taken from the "From: " line of the message, and commit author date is taken from the "Date: " line of the message. The "Subject: " line is used as the title of the commit, after stripping common prefix "[PATCH <anything>]". The "Subject: " line is supposed to concisely describe what the commit is about in one line of text.

"From: ", "Date: ", and "Subject: " lines starting the body override the respective commit author name and title values taken from the headers.

The commit message is formed by the title taken from the "Subject: ", a blank line and the body of the message up to where the patch begins. Excess whitespace at the end of each line is automatically stripped.

The patch is expected to be inline, directly following the message. Any line that is of the form:

is taken as the beginning of a patch, and the commit log message is terminated before the first occurrence of such a line.

When initially invoking git am, you give it the names of the mailboxes to process. Upon seeing the first patch that does not apply, it aborts in the middle. You can recover from this in one of two ways:

The command refuses to process new mailboxes until the current operation is finished, so if you decide to start over from scratch, run git am --abort before running the command with mailbox names.

Before any patches are applied, ORIG_HEAD is set to the tip of the current branch. This is useful if you have problems with multiple commits, like running git am on the wrong branch or an error in the commits that is more easily fixed by changing the mailbox (e.g. errors in the "From:" lines).

This command can run applypatch-msg, pre-applypatch, and post-applypatch hooks. See the section called “githooks(5)” for more information.

Everything below this line in this section is selectively included from the the section called “git-config(1)” documentation. The content is the same as what's found there:

the section called “git-apply(1)”, the section called “git-format-patch(1)”.

Part of the the section called “git(1)” suite

git-annotate - Annotate file lines with commit information

Annotates each line in the given file with information from the commit which introduced the line. Optionally annotates from a given revision.

The only difference between this command and the section called “git-blame(1)” is that they use slightly different output formats, and this command exists only for backward compatibility to support existing scripts, and provide a more familiar command name for people coming from other SCM systems.

the section called “git-blame(1)”

Part of the the section called “git(1)” suite

git-apply - Apply a patch to files and/or to the index

Reads the supplied diff output (i.e. "a patch") and applies it to files. When running from a subdirectory in a repository, patched paths outside the directory are ignored. With the --index option, the patch is also applied to the index, and with the --cached option, the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a Git repository.

This command applies the patch but does not create a commit. Use the section called “git-am(1)” to create commits from patches generated by the section called “git-format-patch(1)” and/or received by email.

Everything below this line in this section is selectively included from the the section called “git-config(1)” documentation. The content is the same as what's found there:

If the patch contains any changes to submodules then git apply treats these changes as follows.

If --index is specified (explicitly or implicitly), then the submodule commits must match the index exactly for the patch to apply. If any of the submodules are checked-out, then these check-outs are completely ignored, i.e., they are not required to be up to date or clean and they are not updated.

If --index is not specified, then the submodule commits in the patch are ignored and only the absence or presence of the corresponding subdirectory is checked and (if possible) updated.

the section called “git-am(1)”.

Part of the the section called “git(1)” suite

git-archimport - Import a GNU Arch repository into Git

Imports a project from one or more GNU Arch repositories. It will follow branches and repositories within the namespaces defined by the <archive>/<branch> parameters supplied. If it cannot find the remote branch a merge comes from it will just import it as a regular commit. If it can find it, it will mark it as a merge whenever possible (see discussion below).

The script expects you to provide the key roots where it can start the import from an initial import or tag type of Arch commit. It will follow and import new branches within the provided roots.

It expects to be dealing with one project only. If it sees branches that have different roots, it will refuse to run. In that case, edit your <archive>/<branch> parameters to define clearly the scope of the import.

git archimport uses tla extensively in the background to access the Arch repository. Make sure you have a recent version of tla available in the path. tla must know about the repositories you pass to git archimport.

For the initial import, git archimport expects to find itself in an empty directory. To follow the development of a project that uses Arch, rerun git archimport with the same parameters as the initial import to perform incremental imports.

While git archimport will try to create sensible branch names for the archives that it imports, it is also possible to specify Git branch names manually. To do so, write a Git branch name after each <archive>/<branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to Git jargon, for example mapping a "PROJECT--devo--VERSION" branch to "master".

Associating multiple Arch branches to one Git branch is possible; the result will make the most sense only if no commits are made to the first branch, after the second branch is created. Still, this is useful to convert Arch repositories that had been rotated periodically.

Patch merge data from Arch is used to mark merges in Git as well. Git does not care much about tracking patches, and only considers a merge when a branch incorporates all the commits since the point they forked. The end result is that Git will have a good idea of how far branches have diverged. So the import process does lose some patch-trading metadata.

Fortunately, when you try and merge branches imported from Arch, Git will find a good merge base, and it has a good chance of identifying patches that have been traded out-of-sequence between the branches.

Part of the the section called “git(1)” suite

git-archive - Create an archive of files from a named tree

Creates an archive of the specified format containing the tree structure for the named tree, and writes it out to the standard output. If <prefix> is specified it is prepended to the filenames in the archive.

git archive behaves differently when given a tree ID as opposed to a commit ID or tag ID. When a tree ID is provided, the current time is used as the modification time of each file in the archive. On the other hand, when a commit ID or tag ID is provided, the commit time as recorded in the referenced commit object is used instead. Additionally the commit ID is stored in a global extended pax header if the tar format is used; it can be extracted using git get-tar-commit-id. In ZIP files it is stored as a file comment.

Note that attributes are by default taken from the .gitattributes files in the tree that is being archived. If you want to tweak the way the output is generated after the fact (e.g. you committed without adding an appropriate export-ignore in its .gitattributes), adjust the checked out .gitattributes file as necessary and use --worktree-attributes option. Alternatively you can keep necessary attributes that should apply while archiving any tree in your $GIT_DIR/info/attributes file.

the section called “gitattributes(5)”

Part of the the section called “git(1)” suite

git-backfill - Download missing objects in a partial clone

Blobless partial clones are created using git clone --filter=blob:none and then configure the local repository such that the Git client avoids downloading blob objects unless they are required for a local operation. This initially means that the clone and later fetches download reachable commits and trees but no blobs. Later operations that change the HEAD pointer, such as git checkout or git merge, may need to download missing blobs in order to complete their operation.

In the worst cases, commands that compute blob diffs, such as git blame, become very slow as they download the missing blobs in single-blob requests to satisfy the missing object as the Git command needs it. This leads to multiple download requests and no ability for the Git server to provide delta compression across those objects.

The git backfill command provides a way for the user to request that Git downloads the missing blobs (with optional filters) such that the missing blobs representing historical versions of files can be downloaded in batches. The backfill command attempts to optimize the request by grouping blobs that appear at the same path, hopefully leading to good delta compression in the packfile sent by the server.

In this way, git backfill provides a mechanism to break a large clone into smaller chunks. Starting with a blobless partial clone with git clone --filter=blob:none and then running git backfill in the local repository provides a way to download all reachable objects in several smaller network calls than downloading the entire repository at clone time.

By default, git backfill downloads all blobs reachable from the HEAD commit. This set can be restricted or expanded using various options.

THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE.

the section called “git-clone(1)”.

Part of the the section called “git(1)” suite

git-bisect - Use binary search to find the commit that introduced a bug

The command takes various subcommands, and different options depending on the subcommand:

git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
                 [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
git bisect (bad|new|<term-new>) [<rev>]
git bisect (good|old|<term-old>) [<rev>...]
git bisect terms [--term-(good|old) | --term-(bad|new)]
git bisect skip [(<rev>|<range>)...]
git bisect reset [<commit>]
git bisect (visualize|view)
git bisect replay <logfile>
git bisect log
git bisect run <cmd> [<arg>...]
git bisect help

This command uses a binary search algorithm to find which commit in your project's history introduced a bug. You use it by first telling it a "bad" commit that is known to contain the bug, and a "good" commit that is known to be before the bug was introduced. Then git bisect picks a commit between those two endpoints and asks you whether the selected commit is "good" or "bad". It continues narrowing down the range until it finds the exact commit that introduced the change.

In fact, git bisect can be used to find the commit that changed any property of your project; e.g., the commit that fixed a bug, or the commit that caused a benchmark's performance to improve. To support this more general usage, the terms "old" and "new" can be used in place of "good" and "bad", or you can choose your own terms. See section "Alternate terms" below for more information.

$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good

Bisecting: 675 revisions left to test after this (roughly 10 steps)

$ git bisect good

$ git bisect bad

Bisecting: 337 revisions left to test after this (roughly 9 steps)

$ git bisect reset

$ git bisect reset <commit>

git bisect old [<rev>]

git bisect new [<rev>...]

git bisect terms

git bisect start --term-old <term-old> --term-new <term-new>

git bisect start --term-old fast --term-new slow

git bisect start --term-new fixed --term-old broken

$ git bisect visualize

$ git bisect visualize --stat

$ git bisect log

$ git bisect reset
$ git bisect replay that-file

$ git bisect good/bad                   # previous round was good or bad.
Bisecting: 337 revisions left to test after this (roughly 9 steps)
$ git bisect visualize                  # oops, that is uninteresting.
$ git reset --hard HEAD~3               # try 3 revisions before what
                                        # was suggested

$ git bisect skip                 # Current version cannot be tested

$ git bisect skip v2.5..v2.6

$ git bisect skip v2.5 v2.5..v2.6

$ git bisect start -- arch/i386 include/asm-i386

$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
                   # v2.6.20-rc6 is bad
                   # v2.6.20-rc4 and v2.6.20-rc1 are good

$ git bisect run my_script arguments

Fighting regressions with git bisect, the section called “git-blame(1)”.

Part of the the section called “git(1)” suite

git-blame - Show what revision and author last modified each line of a file

Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision.

When specified one or more times, -L restricts annotation to the requested lines.

The origin of lines is automatically followed across whole-file renames (currently there is no option to turn the rename-following off). To follow lines moved from one file to another, or to follow lines that were copied and pasted from another file, etc., see the -C and -M options.

The report does not tell you anything about lines which have been deleted or replaced; you need to use a tool such as git diff or the "pickaxe" interface briefly mentioned in the following paragraph.

Apart from supporting file annotation, Git also supports searching the development history for when a code snippet occurred in a change. This makes it possible to track when a code snippet was added to a file, moved or copied between files, and eventually deleted or replaced. It works by searching for a text string in the diff. A small example of the pickaxe interface that searches for blame_usage:

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

When neither --porcelain nor --incremental option is specified, git blame will output annotation for each line with:

before the line contents.

In this format, each line is output after a header; the header at the minimum has the first line which has:

This header line is followed by the following information at least once for each commit:

The contents of the actual line are output after the above header, prefixed by a TAB. This is to allow adding more header elements later.

The porcelain format generally suppresses commit information that has already been seen. For example, two lines that are blamed to the same commit will both be shown, but the details for that commit will be shown only once. Information which is specific to individual lines will not be grouped together, like revs to be marked ignored or unblamable. This is more efficient, but may require more state be kept by the reader. The --line-porcelain option can be used to output full commit information for each line, allowing simpler (but less efficient) usage like:

# count the number of lines attributed to each author
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

Unlike git blame and git annotate in older versions of git, the extent of the annotation can be limited to both line ranges and revision ranges. The -L option, which limits annotation to a range of lines, may be specified multiple times.

When you are interested in finding the origin for lines 40-60 for file foo, you can use the -L option like so (they mean the same thing -- both ask for 21 lines starting at line 40):

git blame -L 40,60 foo
git blame -L 40,+21 foo

Also you can use a regular expression to specify the line range:

git blame -L '/^sub hello {/,/^}$/' foo

which limits the annotation to the body of the hello subroutine.

When you are not interested in changes older than version v2.6.18, or changes older than 3 weeks, you can use revision range specifiers similar to git rev-list:

git blame v2.6.18.. -- foo
git blame --since=3.weeks -- foo

When revision range specifiers are used to limit the annotation, lines that have not changed since the range boundary (either the commit v2.6.18 or the most recent commit that is more than 3 weeks old in the above example) are blamed for that range boundary commit.

A particularly useful way is to see if an added file has lines created by copy-and-paste from existing files. Sometimes this indicates that the developer was being sloppy and did not refactor the code properly. You can first find the commit that introduced the file with:

git log --diff-filter=A --pretty=short -- foo

and then annotate the change between the commit and its parents, using commit^! notation:

git blame -C -C -f $commit^! -- foo

When called with --incremental option, the command outputs the result as it is built. The output generally will talk about lines touched by more recent commits first (i.e. the lines will be annotated out of order) and is meant to be used by interactive viewers.

The output format is similar to the Porcelain format, but it does not contain the actual lines from the file that is being annotated.

See the section called “gitmailmap(5)”.

Everything below this line in this section is selectively included from the the section called “git-config(1)” documentation. The content is the same as what's found there:

the section called “git-annotate(1)”

Part of the the section called “git(1)” suite

git-branch - List, create, or delete branches

If --list is given, or if there are no non-option arguments, existing branches are listed; the current branch will be highlighted in green and marked with an asterisk. Any branches checked out in linked worktrees will be highlighted in cyan and marked with a plus sign. Option -r causes the remote-tracking branches to be listed, and option -a shows both local and remote branches.

If a <pattern> is given, it is used as a shell wildcard to restrict the output to matching branches. If multiple patterns are given, a branch is shown if it matches any of the patterns.

Note that when providing a <pattern>, you must use --list; otherwise the command may be interpreted as branch creation.

With --contains, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the named commit), --no-contains inverts it. With --merged, only branches merged into the named commit (i.e. the branches whose tip commits are reachable from the named commit) will be listed. With --no-merged only branches not merged into the named commit will be listed. If the <commit> argument is missing it defaults to HEAD (i.e. the tip of the current branch).

The command's second form creates a new branch head named <branch-name> which points to the current HEAD, or <start-point> if given. As a special case, for <start-point>, you may use <rev-A>...<rev-B> as a shortcut for the merge base of <rev-A> and <rev-B> if there is exactly one merge base. You can leave out at most one of <rev-A> and <rev-B>, in which case it defaults to HEAD.

Note that this will create the new branch, but it will not switch the working tree to it; use git switch <new-branch> to switch to the new branch.

When a local branch is started off a remote-tracking branch, Git sets up the branch (specifically the branch.<name>.remote and branch.<name>.merge configuration entries) so that git pull will appropriately merge from the remote-tracking branch. This behavior may be changed via the global branch.autoSetupMerge configuration flag. That setting can be overridden by using the --track and --no-track options, and changed later using git branch --set-upstream-to.

With a -m or -M option, <old-branch> will be renamed to <new-branch>. If <old-branch> had a corresponding reflog, it is renamed to match <new-branch>, and a reflog entry is created to remember the branch renaming. If <new-branch> exists, -M must be used to force the rename to happen.

The -c and -C options have the exact same semantics as -m and -M, except instead of the branch being renamed, it will be copied to a new name, along with its config and reflog.

With a -d or -D option, <branch-name> will be deleted. You may specify more than one branch for deletion. If the branch currently has a reflog then the reflog will also be deleted.

Use -r together with -d to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist in the remote repository or if git fetch was configured not to fetch them again. See also the prune subcommand of the section called “git-remote(1)” for a way to clean up all obsolete remote-tracking branches.

pager.branch is only respected when listing branches, i.e., when --list is used or implied. The default is to use a pager. See the section called “git-config(1)”.

Everything above this line in this section isn't included from the the section called “git-config(1)” documentation. The content that follows is the same as what's found there:

Patterns will normally need quoting.

If you are creating a branch that you want to switch to immediately, it is easier to use the git switch command with its -c option to do the same thing with a single command.

The options --contains, --no-contains, --merged and --no-merged serve four related but different purposes:

When combining multiple --contains and --no-contains filters, only references that contain at least one of the --contains commits and contain none of the --no-contains commits are shown.

When combining multiple --merged and --no-merged filters, only references that are reachable from at least one of the --merged commits and from none of the --no-merged commits are shown.

the section called “git-check-ref-format(1)”, the section called “git-fetch(1)”, the section called “git-remote(1)”, "Understanding history: What is a branch?" in the Git User's Manual.

Part of the the section called “git(1)” suite

git-bugreport - Collect information for user to file a bug report

Collects information about the user's machine, Git client, and repository state, in addition to a form requesting information about the behavior the user observed, and stores it in a single text file which the user can then share, for example to the Git mailing list, in order to report an observed bug.

The following information is requested from the user:

The following information is captured automatically:

Additional information may be gathered into a separate zip archive using the --diagnose option, and can be attached alongside the bugreport document to provide additional context to readers.

This tool is invoked via the typical Git setup process, which means that in some cases, it might not be able to launch - for example, if a relevant config file is unreadable. In this kind of scenario, it may be helpful to manually gather the kind of information listed above when manually asking for help.

Part of the the section called “git(1)” suite

git-bundle - Move objects and refs by archive

Create, unpack, and manipulate "bundle" files. Bundles are used for the "offline" transfer of Git objects without an active "server" sitting on the other side of the network connection.

They can be used to create both incremental and full backups of a repository (see the "full backup" example in "EXAMPLES"), and to relay the state of the references in one repository to another (see the second example).

Git commands that fetch or otherwise "read" via protocols such as ssh:// and https:// can also operate on bundle files. It is possible the section called “git-clone(1)” a new repository from a bundle, to use the section called “git-fetch(1)” to fetch from one, and to list the references contained within it with the section called “git-ls-remote(1)”. There's no corresponding "write" support, i.e. a git push into a bundle is not supported.

Bundles are .pack files (see the section called “git-pack-objects(1)”) with a header indicating what references are contained within the bundle.

Like the packed archive format itself bundles can either be self-contained, or be created using exclusions. See the "OBJECT PREREQUISITES" section below.

Bundles created using revision exclusions are "thin packs" created using the --thin option to the section called “git-pack-objects(1)”, and unbundled using the --fix-thin option to the section called “git-index-pack(1)”.

There is no option to create a "thick pack" when using revision exclusions, and users should not be concerned about the difference. By using "thin packs", bundles created using exclusions are smaller in size. That they're "thin" under the hood is merely noted here as a curiosity, and as a reference to other documentation.

See the section called “gitformat-bundle(5)” for more details and the discussion of "thin pack" in the section called “gitformat-pack(5)” for further details.

Revisions must be accompanied by reference names to be packaged in a bundle. Alternatively --all can be used to package all refs.

More than one reference may be packaged, and more than one set of prerequisite objects can be specified. The objects packaged are those not contained in the union of the prerequisites.

The git bundle create command resolves the reference names for you using the same rules as git rev-parse --abbrev-ref=loose. Each prerequisite can be specified explicitly (e.g. ^master~10), or implicitly (e.g. master~10..master, --since=10.days.ago master).

All of these simple cases are OK (assuming we have a "master" and "next" branch):

$ git bundle create master.bundle master
$ echo master | git bundle create master.bundle --stdin
$ git bundle create master-and-next.bundle master next
$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin

And so are these (and the same but omitted --stdin examples):

$ git bundle create recent-master.bundle master~10..master
$ git bundle create recent-updates.bundle master~10..master next~5..next

A revision name or a range whose right-hand-side cannot be resolved to a reference is not accepted:

$ git bundle create HEAD.bundle $(git rev-parse HEAD)
fatal: Refusing to create empty bundle.
$ git bundle create master-yesterday.bundle master~10..master~5
fatal: Refusing to create empty bundle.

When creating bundles it is possible to create a self-contained bundle that can be unbundled in a repository with no common history, as well as providing negative revisions to exclude objects needed in the earlier parts of the history.

Feeding a revision such as new to git bundle create will create a bundle file that contains all the objects reachable from the revision new. That bundle can be unbundled in any repository to obtain a full history that leads to the revision new:

$ git bundle create full.bundle new

A revision range such as old..new will produce a bundle file that will require the revision old (and any objects reachable from it) to exist for the bundle to be "unbundle"-able:

$ git bundle create full.bundle old..new

A self-contained bundle without any prerequisites can be extracted into anywhere, even into an empty repository, or be cloned from (i.e., new, but not old..new).

It is okay to err on the side of caution, causing the bundle file to contain objects already in the destination, as these are ignored when unpacking at the destination.

If you want to provide the same set of refs that a clone directly from the source repository would get, use --branches --tags for the <git-rev-list-args>.

The git bundle verify command can be used to check whether your recipient repository has the required prerequisite commits for a bundle.

We'll discuss two cases:

First let's consider a full backup of the repository. The following command will take a full backup of the repository in the sense that all refs are included in the bundle:

$ git bundle create backup.bundle --all

But note again that this is only for the refs, i.e. you will only include refs and commits reachable from those refs. You will not include other local state, such as the contents of the index, working tree, the stash, per-repository configuration, hooks, etc.

You can later recover that repository by using for example the section called “git-clone(1)”:

$ git clone backup.bundle <new directory>

For the next example, assume you want to transfer the history from a repository R1 on machine A to another repository R2 on machine B. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1.

To bootstrap the process, you can first create a bundle that does not have any prerequisites. You can use a tag to remember up to what commit you last processed, in order to make it easy to later update the other repository with an incremental bundle:

machineA$ cd R1
machineA$ git bundle create file.bundle master
machineA$ git tag -f lastR2bundle master

Then you transfer file.bundle to the target machine B. Because this bundle does not require any existing object to be extracted, you can create a new repository on machine B by cloning from it:

machineB$ git clone -b master /home/me/tmp/file.bundle R2

This will define a remote called "origin" in the resulting repository that lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will have an entry like this:

[remote "origin"]
    url = /home/me/tmp/file.bundle
    fetch = refs/heads/*:refs/remotes/origin/*

To update the resulting mine.git repository, you can fetch or pull after replacing the bundle stored at /home/me/tmp/file.bundle with incremental updates.

After working some more in the original repository, you can create an incremental bundle to update the other repository:

machineA$ cd R1
machineA$ git bundle create file.bundle lastR2bundle..master
machineA$ git tag -f lastR2bundle master

You then transfer the bundle to the other machine to replace /home/me/tmp/file.bundle, and pull from it.

machineB$ cd R2
machineB$ git pull

If you know up to what commit the intended recipient repository should have the necessary objects, you can use that knowledge to specify the prerequisites, giving a cut-off point to limit the revisions and objects that go in the resulting bundle. The previous example used the lastR2bundle tag for this purpose, but you can use any other options that you would give to the the section called “git-log(1)” command. Here are more examples:

You can use a tag that is present in both:

$ git bundle create mybundle v1.0.0..master

You can use a prerequisite based on time:

$ git bundle create mybundle --since=10.days master

You can use the number of commits:

$ git bundle create mybundle -10 master

You can run git-bundle verify to see if you can extract from a bundle that was created with a prerequisite:

$ git bundle verify mybundle

This will list what commits you must have in order to extract from the bundle and will error out if you do not have them.

A bundle from a recipient repository's point of view is just like a regular repository which it fetches or pulls from. You can, for example, map references when fetching:

$ git fetch mybundle master:localRef

You can also see what references it offers:

$ git ls-remote mybundle

A naive way to make a full backup of a repository is to use something to the effect of cp -r <repo> <destination>. This is discouraged since the repository could be written to during the copy operation. In turn some files at <destination> could be corrupted.

This is why it is recommended to use Git tooling for making repository backups, either with this command or with e.g. the section called “git-clone(1)”. But keep in mind that these tools will not help you backup state other than refs and commits. In other words they will not help you backup contents of the index, working tree, the stash, per-repository configuration, hooks, etc.

See also the section called “gitfaq(7)”, section "TRANSFERS" for a discussion of the problems associated with file syncing across systems.

See the section called “gitformat-bundle(5)”.

Part of the the section called “git(1)” suite

git-cat-file - Provide contents or details of repository objects

Output the contents or other properties such as size, type or delta information of one or more objects.

This command can operate in two modes, depending on whether an option from the --batch family is specified.

In non-batch mode, the command provides information on an object named on the command line.

In batch mode, arguments are read from standard input.

If -t is specified, one of the <type>.

If -s is specified, the size of the <object> in bytes.

If -e is specified, no output, unless the <object> is malformed.

If -p is specified, the contents of <object> are pretty-printed.

If <type> is specified, the raw (though uncompressed) contents of the <object> will be returned.

If --batch or --batch-check is given, cat-file will read objects from stdin, one per line, and print information about them in the same order as they have been read. By default, the whole line is considered as an object, as if it were fed to the section called “git-rev-parse(1)”.

When --batch-command is given, cat-file will read commands from stdin, one per line, and print information based on the command given. With --batch-command, the info command followed by an object will print information about the object the same way --batch-check would, and the contents command followed by an object prints contents in the same way --batch would.

You can specify the information shown for each object by using a custom <format>. The <format> is copied literally to stdout for each object, with placeholders of the form %(atom) expanded, followed by a newline. The available atoms are:

If no format is specified, the default format is %(objectname) %(objecttype) %(objectsize).

If --batch is specified, or if --batch-command is used with the contents command, the object information is followed by the object contents (consisting of %(objectsize) bytes), followed by a newline.

For example, --batch without a custom format would produce:

<oid> SP <type> SP <size> LF
<contents> LF

Whereas --batch-check='%(objectname) %(objecttype)' would produce:

<oid> SP <type> LF

If a name is specified on stdin that cannot be resolved to an object in the repository, then cat-file will ignore any custom format and print:

<object> SP missing LF

If a name is specified on stdin that is filtered out via --filter=, then cat-file will ignore any custom format and print:

<object> SP excluded LF

If a name is specified that might refer to more than one object (an ambiguous short sha), then cat-file will ignore any custom format and print:

<object> SP ambiguous LF

If --follow-symlinks is used, and a symlink in the repository points outside the repository, then cat-file will ignore any custom format and print:

symlink SP <size> LF
<symlink> LF

The symlink will either be absolute (beginning with a /), or relative to the tree root. For instance, if dir/link points to ../../foo, then <symlink> will be ../foo. <size> is the size of the symlink in bytes.

If --follow-symlinks is used, the following error messages will be displayed:

<object> SP missing LF

is printed when the initial symlink requested does not exist.

dangling SP <size> LF
<object> LF

is printed when the initial symlink exists, but something that it (transitive-of) points to does not.

loop SP <size> LF
<object> LF

is printed for symlink loops (or any symlinks that require more than 40 link resolutions to resolve).

notdir SP <size> LF
<object> LF

is printed when, during symlink resolution, a file is used as a directory name.

Alternatively, when -Z is passed, the line feeds in any of the above examples are replaced with NUL terminators. This ensures that output will be parsable if the output itself would contain a linefeed and is thus recommended for scripting purposes.

Note that the sizes of objects on disk are reported accurately, but care should be taken in drawing conclusions about which refs or objects are responsible for disk usage. The size of a packed non-delta object may be much larger than the size of objects which delta against it, but the choice of which object is the base and which is the delta is arbitrary and is subject to change during a repack.

Note also that multiple copies of an object may be present in the object database; in this case, it is undefined which copy's size or delta base will be reported.

Part of the the section called “git(1)” suite

git-check-attr - Display gitattributes information

For every pathname, this command will list if each attribute is unspecified, set, or unset as a gitattribute on that pathname.

If none of --stdin, --all, or -- is used, the first argument will be treated as an attribute and the rest of the arguments as pathnames.

The output is of the form: <path> COLON SP <attribute> COLON SP <info> LF

unless -z is in effect, in which case NUL is used as delimiter: <path> NUL <attribute> NUL <info> NUL

<path> is the path of a file being queried, <attribute> is an attribute being queried, and <info> can be either:

Buffering happens as documented under the GIT_FLUSH option in the section called “git(1)”. The caller is responsible for avoiding deadlocks caused by overfilling an input buffer or reading from an empty output buffer.

In the examples, the following .gitattributes file is used:

*.java diff=java -crlf myAttr
NoMyAttr.java !myAttr
README caveat=unspecified

the section called “gitattributes(5)”.

Part of the the section called “git(1)” suite

git-check-ignore - Debug gitignore / exclude files

For each pathname given via the command-line or from a file via --stdin, check whether the file is excluded by .gitignore (or other input files to the exclude mechanism) and output the path if it is excluded.

By default, tracked files are not shown at all since they are not subject to exclude rules; but see --no-index.

By default, any of the given pathnames which match an ignore pattern will be output, one per line. If no pattern matches a given path, nothing will be output for that path; this means that path will not be ignored.

If --verbose is specified, the output is a series of lines of the form:

<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>

<pathname> is the path of a file being queried, <pattern> is the matching pattern, <source> is the pattern's source file, and <linenum> is the line number of the pattern within that source. If the pattern contained a "!" prefix or "/" suffix, it will be preserved in the output. <source> will be an absolute path when referring to the file configured by core.excludesFile, or relative to the repository root when referring to .git/info/exclude or a per-directory exclude file.

If -z is specified, the pathnames in the output are delimited by the null character; if --verbose is also specified then null characters are also used instead of colons and hard tabs:

<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>

If -n or --non-matching are specified, non-matching pathnames will also be output, in which case all fields in each output record except for <pathname> will be empty. This can be useful when running non-interactively, so that files can be incrementally streamed to STDIN of a long-running check-ignore process, and for each of these files, STDOUT will indicate whether that file matched a pattern or not. (Without this option, it would be impossible to tell whether the absence of output for a given file meant that it didn't match any pattern, or that the output hadn't been generated yet.)

Buffering happens as documented under the GIT_FLUSH option in the section called “git(1)”. The caller is responsible for avoiding deadlocks caused by overfilling an input buffer or reading from an empty output buffer.

the section called “gitignore(5)” the section called “git-config(1)” the section called “git-ls-files(1)”

Part of the the section called “git(1)” suite

git-check-mailmap - Show canonical names and email addresses of contacts

For each Name <user@host>, <user@host>, or user@host from the command-line or standard input (when using --stdin), look up the person's canonical name and email address (see "Mapping Authors" below). If found, print them; otherwise print the input as-is.

For each contact, a single line is output, terminated by a newline. If the name is provided or known to the mailmap, Name <user@host> is printed; otherwise only <user@host> is printed.

See mailmap.file and mailmap.blob in the section called “git-config(1)” for how to specify a custom .mailmap target file or object.

See the section called “gitmailmap(5)”.

Part of the the section called “git(1)” suite

git-check-ref-format - Ensures that a reference name is well formed

Checks if a given refname is acceptable, and exits with a non-zero status if it is not.

A reference is used in Git to specify branches and tags. A branch head is stored in the refs/heads hierarchy, while a tag is stored in the refs/tags hierarchy of the ref namespace (typically in $GIT_DIR/refs/heads and $GIT_DIR/refs/tags directories or, as entries in file $GIT_DIR/packed-refs if refs are packed by git gc).

Git imposes the following rules on how references are named:

These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoid ambiguities in certain reference name expressions (see the section called “gitrevisions(7)”):

With the --branch option, the command takes a name and checks if it can be used as a valid branch name (e.g. when creating a new branch). But be cautious when using the previous checkout syntax that may refer to a detached HEAD state. The rule git check-ref-format --branch $name implements may be stricter than what git check-ref-format refs/heads/$name says (e.g. a dash may appear at the beginning of a ref component, but it is explicitly forbidden at the beginning of a branch name). When run with the --branch option in a repository, the input is first expanded for the previous checkout syntax @{-n}. For example, @{-1} is a way to refer the last thing that was checked out using "git switch" or "git checkout" operation. This option should be used by porcelains to accept this syntax anywhere a branch name is expected, so they can act as if you typed the branch name. As an exception note that, the previous checkout operation might result in a commit object name when the N-th last thing checked out was not a branch.

Part of the the section called “git(1)” suite

git-checkout-index - Copy files from the index to the working tree

Copies all listed files from the index to the working directory (not overwriting existing files).

The order of the flags used to matter, but not anymore.

Just doing git checkout-index does nothing. You probably meant git checkout-index -a. And if you want to force it, you want git checkout-index -f -a.